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ABOUT THIS CHAPTER 


Warning: This chapter has not been updated to reflect changes and improvements 
that are available on systems using 32-Bit QuickDraw. For further 
information on 32-Bit QuickDraw, please refer to the 32-Bit QuickDraw 
documentation (available on "Phil & Dave's Excellent CD: The Release 
Version). 


This chapter describes the Color Picker, a package that allows applications to 
present users with a standard interface for color selection. You should be 
familiar with color on the Macintosh and graphic devices, as discussed in the 
Color QuickDraw and Graphic Devices chapters. 
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THE COLOR PICKER PACKAGE 


The Color Picker Package is a tool that applications can use to present a 
standard user interface for color selection. It also provides routines for 
converting color values between several different color systems. The Color 
Picker Package does not alter the Color Look-Up Table (CLUT), if any, associated 
with the current graphics device. 


Once the user chooses a color, Color Picker returns it to the application, in 
the form of an RGBColor value, leaving the graphics device in its original 
state. The application can do what it likes with the color selection, with as 
much or as little attention to the available graphics hardware as it deems 
appropriate. On black and white hardware (or in less than 4-bit mode), the 
display is in black and white; Color Picker returns the value selected, but does 
not call any color routines. 


On direct device hardware the exact color can be used without extra effort, 
while on fixed CLUT hardware it can only be approximated. On most hardware, 
such as Apple's TFB graphics card, which has a variable CLUT, the application 
decides how faithfully to reproduce the color, because it can replace an entry 
in the device's CLUT to show it exactly, or treat the table as fixed and 
approximate the color. Color Picker itself takes advantage of the hardware on 
such devices, displaying the exact color by borrowing a color table entry. As 
result, applications that are content to approximate the color will show users 
colors that differ somewhat from the ones picked. 
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THE COLOR PICKER DIALOG BOX 


Developers can present the Color Picker dialog box, shown in Figures 1 & 2 

(This illustration is in color in Figure 1 if you are using a color monitor in 
color mode.), to a user by means of the Color Picker routine, described later in 
this chapter. 


select a highlight color. 


Saturation | 62929 
Brightness [65535 


Green 


Blue 


Figure 1-Color Picker Dialog Box (Color Yersion) 


Figure 1—Color Picker Dialog Box (Color Version) 
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Select a highlight color. 


Saturation | 62923 
Brightness [65535 


Red [65535 | 


Green | 3858 


we 


Figure 2-Color Picker Dialog Bor (Biv Yersion) 
Figure 2—Color Picker Dialog Box (B/W Version) 


When called by an application, the Color Picker supplies the prompt text, which 
appears in the upper-left corner, and the initial color, which appears in the 
bottom of the two rectangles below the prompt. The color being picked, in the 
upper rectangle, ranges rapidly over the entire color space, in response to the 
controls in the rest of the dialog. The calling application also supplies the 
location of the top-left corner of the dialog window. 


The user is allowed to select a single color, from the entire range the hardware 
can produce. The wheel allows users to select a given hue and saturation 
simultaneously. The center of the wheel displays zero saturation 

(no hue mixed in); the outer boundary is maximum saturation (no gray mixed in); 
colors on the edge of the wheel are pure hues. The scroll bar at right controls 
the brightness (value) of the wheel. 


The two groups of text fields (Hue/Saturation/Brightness and Red/Green/Blue) 
show the parameters of the color being picked in two independent color systems. 
Brightness represents value in the HSV model. 


The HSV values are the primary color system, which correspond to the controls in 
the dialog box. The RGB values are the alternate color system, and the way they 
vary in response to the dialog controls is not intuitive. Only users who 
understand both color systems will understand how the RGB values vary in 
relation to the rest of the dialog. (See the Color Quickdraw chapter for more 
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information.) The alternate color system is intended to make life easier for 
users accustomed to something other than the HSV model. 


The range for all of the component values is 0 to 65,535. Larger values are 
clipped to the maximum after the user exits the field. When incrementing or 
decrementing the hue via the arrow controls, 0 wraps around to 65,535, and vice 
versa, so the user can circumnavigate the wheel unimpeded. The hue value for 
red is 0; green is 21,845; blue is 43,690. 
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COLOR PICKER PACKAGE ROUTINES 


FUNCTION GetColor(where: Point; prompt: Str255; inColor: RGBColor; 
VAR outColor: RGBColor) : BOOLEAN; 


GetColor displays the Color Picker dialog box on the screen, with its top-left 
corner located at where. (The where Point should be on the main gDevice.) If 
where = (0,0), the dialog box is positioned neatly on the screen, centered 
horizontally, and with one third of the empty space above the box, two thirds 
below, whatever the screen size. 


The prompt string is displayed in the upper-left corner of the dialog box. 
InColor is the starting color, which the user may want for comparison, and is 
displayed immediately below the current output color (the one the user is 
picking). OutColor is set to the last color value the user picked, if and only 
if the user clicks OK. On entry, it is treated as undefined, so the output 
color sample originally matches the input. While the color being picked may 
vary widely, the input color sample remains fixed, and clicking in the input 
sample resets the output color sample to match it. 


GetColor returns TRUE if the user exits via the OK button, or FALSE if the user 
cancels. 


Assembly-language note: the trap macro for the Color Picker Package is 
_Pack12. The routine selectors are as follows: 


Fix2SmallFract .EQU 1 
SmallFract2Fix .EQU 2 
CMY2RGB . EQU 3 
RGB2CMY . EQU 4 
HSL2RGB .EQU 5 
RGB2HSL .EQU 6 
HSV2RGB . EQU 7 
RGB2HSV . EQU 8 
GetColor . EQU 9 
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CONVERSION FACILITIES 


The Color Picker provides six procedures for converting color values between CMY 
and RGB, and between HSL or HSV and RGB. Most developers will not need to use 
these routines. 
PROCEDURE CMY2RGB (cColor: CMYColor; VAR rColor: RGBColor); 

PROCEDURE RGB2CMY (rColor: RGBColor; VAR cColor: CMYColor); 

PROCEDURE HSL2RGB (hColor: HSLColor; VAR rColor: RGBColor); 

PROCEDURE RGB2HSL (rColor: RGBColor; VAR hColor: HSLColor); 

PROCEDURE HSV2RGB (hColor: HSVColor; VAR rColor: RGBColor); 

PROCEDURE RGB2HSV (rColor: RGBColor; VAR hColor: HSVColor); 

For developmental simplicity in switching between the HLS and HSV models, HLS is 
reordered into HSL. Thus both models start with hue and saturation values; 
value/lightness/brightness is last. 


The CMY, HSL, and HSV structures are defined by ColorPicker with SmallFract 
values rather than INTEGER values (as in RGBColor). A SmallFract value is the 
fractional part of a Fixed number, which is the low-order word. The INTEGER 
values in RGBColor are actually used as unsigned integer-sized values; by using 
SmallFracts, ColorPicker avoids sign extension problems in the conversion math. 


The Color Picker provides two functions for converting between SmallFract and 
Fixed numbers. Most developers will not need to use these facilities. 


FUNCTION Fix2SmallFract(f: Fixed): SmallFract; 
FUNCTION SmallFract2Fix(s: SmallFract): Fixed; 


A SmallFract can represent a value between 0 and 65,535. They can be assigned 
directly to and from INTEGERs. 
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SUMMARY OF THE COLOR PICKER PACKAGE 


Constants 
CONST 
MaxSmallFract = $Q0000FFFF; {maximum SmallFract value, as LONGINT} 
Data Types 
TYPE 
SmallFract = INTEGER; {unsigned fraction between 0 and 1} 
HSVColor = RECORD 
hue: SmallFract; {fraction of circle, red at 0} 
saturation: SmallFract; {0-1, 0 is gray, 1 is pure color} 
value: SmallFract; {0-1, 0 is black, 1 is max intensity} 
END; 
HSLColor = RECORD 
hue: SmallFract; {fraction of circle, red at 0} 
saturation: SmallFract; {0-1, 0 is gray, 1 is pure color} 
lightness: SmallFract; {0-1, 0 is black, 1 is white} 
END; 
CMYColor = RECORD {CMY and RGB are complements} 
cyan: SmallFract; 
magenta: SmallFract; 
yellow: SmallFract; 
END; 
Routines 


FUNCTION GetColor(where: Point; prompt: Str255; inColor: RGBColor; 
VAR outColor: RGBColor): BOOLEAN; 


Conversion Functions 


FUNCTION Fix2SmallFract(f: Fixed): 
FUNCTION SmallFract2Fix(s: 


SmallFract; 
SmallFract): Fixed; 


Color Conversion Procedures 


PROCEDURE CMY2RGB(cColor: 
PROCEDURE RGB2CMY(rColor: 


( CMYColor; 

( 
PROCEDURE HSL2RGB(hColor: 

( 

( 


RGBColor; 
HSLColor; 
RGBColor; 
HSVColor; 


VAR 
VAR 
VAR 
VAR 
VAR 


RGBColor 
CMYColor 


rColor: 5 
ey 
RGBColor); 
ya 
G 


cColor: 
rColor: 
hColor: 
rColor: 


PROCEDURE RGB2HSL(rColor: 
PROCEDURE HSV2RGB(hColor: 


HSLColor 
RGBColor 
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PROCEDURE RGB2HSV(rColor: RGBColor; VAR hColor: HSVColor); 


Assembly-Language Information 


Constants 

Fix2SmallFract .EQU 1 
SmallFract2Fix .EQU 2 
CMY2RGB . EQU 3 
RGB2CMY . EQU 4 
HSL2RGB . EQU 5 
RGB2HSL . EQU 6 
HSV2RGB . EQU 7 
RGB2HSV . EQU 8 
GetColor . EQU 9 
Macro 

_PACK12 
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Further Reference: 


Color QuickDraw 
Graphics Devices 
32-Bit QuickDraw Documentation 


END OF DOCUMENT 
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